home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Sample Code / Interapplication Comm / MoreOSL / MoreOSL / MoreOSLTokens.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-09-28  |  6.0 KB  |  129 lines  |  [TEXT/CWIE]
  1. /*
  2.     File:        MoreOSLTokens.h
  3.  
  4.     Contains:    Token definition for MoreOSL.
  5.  
  6.     Written by:    Quinn
  7.  
  8.     Copyright:    Copyright © 2000 by Apple Computer, Inc., all rights reserved.
  9.  
  10.                 You may incorporate this Apple sample source code into your program(s) without
  11.                 restriction. This Apple sample source code has been provided "AS IS" and the
  12.                 responsibility for its operation is yours. You are not permitted to redistribute
  13.                 this Apple sample source code as "Apple sample source code" after having made
  14.                 changes. If you're going to re-distribute the source, we require that you make
  15.                 it clear in the source that the code was descended from Apple sample source
  16.                 code, but that you've made changes.
  17.  
  18.     Change History (most recent first):
  19.  
  20.          <2>     20/3/00    Quinn   Added InitPropertyMOSLTokenFromOtherProperty.
  21.          <1>      6/3/00    Quinn   First checked in.
  22. */
  23.  
  24. #pragma once
  25.  
  26. /////////////////////////////////////////////////////////////////
  27.  
  28. // MoreIsBetter Setup
  29.  
  30. #include "MoreSetup.h"
  31.  
  32. // Mac OS Interfaces
  33.  
  34. #include <AppleEvents.h>
  35.  
  36. /////////////////////////////////////////////////////////////////
  37.  
  38. // Big Picture
  39. // -----------
  40. // MOSLToken in the OSL token type used by MoreOSL (MOSL).  In general, the OSL
  41. // token for an application is the application’s responsibility.  However,
  42. // in MoreOSL I’ve designed a fairly generic token structure that maps well
  43. // to common application structures.  I’ve then made this token structure
  44. // part of MOSL so that MOSL can do more than the vanilla OSL (hence the name).
  45. // You sacrifice some flexibility of token design, but you get a lot of extra
  46. // functionality back.
  47. //
  48. // However, I do recognise that there may be circumstances under which you want
  49. // to keep MOSL but expand the token format.  So, I’ve broken the MOSLToken
  50. // data structure, and the routines that directly operate upon it, out of the
  51. // "MoreOSL.[hc]" files and placed them here.  This way you can take updates
  52. // to MOSL while preserving any token structure modifications you need.
  53. //
  54. // MOSLToken Structure
  55. // -------------------
  56. // A MOSLToken can either represent an object, or an object’s property.
  57. // Various fields of the record are used in various ways depending on
  58. // what the token represents.
  59. //
  60. //       o    tokType is either the type of the object that this token represents,
  61. //      or typeProperty for properties.  If tokType is not typeProperty, it 
  62. //      must be the same as tokObjType.
  63. //    o    tokObjType is the type of the object or, if tokType is typeProperty,
  64. //        the type of the object that has the property.  This value is always
  65. //      the same four character code as the classID field of a class in the
  66. //        class table.  You can look up this value in the class table
  67. //        to determine the appropriate accessors to call for this token,
  68. //        regardless of whether its an object or a property.
  69. //    o tokPropName is either the name of the property that this token
  70. //        represents, or 0 if the token represents an object.
  71. //    o tokData is a pointer to the application ‘native’ object represented
  72. //      by this token.  MOSL does not look at or modify this field (other
  73. //        than in the token init routines described below).  You might store
  74. //         a C++ object pointer in this field.
  75.  
  76. struct MOSLToken {
  77.     DescType tokType;            // type of object, typeProperty for properties
  78.     DescType tokObjType;        // type of object, when tokType is typeProperty, this is the type of the parent object, otherwise same as tokType
  79.     DescType tokPropName;        // when tokType is typeProperty, this is the property name, otherwise n/a
  80.     void     *tokData;            // pointer to application object
  81. };
  82. typedef struct MOSLToken MOSLToken, *MOSLTokenPtr;
  83.  
  84. #if MORE_DEBUG
  85.     extern pascal void BBLogMOSLToken(ConstStr255Param tag, const MOSLToken *tok);
  86.         // Logs a textual representation of the token to BBEdit.
  87.         // This routine is very much like the data logging routines
  88.         // in MoreBBLog, but it resides here to avoid layer breaking
  89.         // (I don’t want "MoreBBLog.[hc]" being dependent on "MoreOSLTokens.h").
  90. #else
  91.     #define BBLogMOSLToken(tag, tok)
  92. #endif
  93.  
  94. extern pascal void     InitObjectMOSLToken(MOSLToken *tok, DescType tokType, void *tokData);
  95.     // Initialises a token to reference an object of type tokType whose
  96.     // native object pointer is tokData.
  97.     
  98. extern pascal void     InitPropertyMOSLToken(MOSLToken *tok, DescType tokObjType, DescType tokPropName, void *tokData);
  99.     // Initialises a token to reference a property of name tokPropName of
  100.     // an object whose type is tokType and whose native object pointer is tokData.
  101.     
  102. extern pascal void     InitPropertyMOSLTokenFromContainer(MOSLToken *tok, const MOSLToken *containerTok, DescType tokPropName);
  103.     // Initialises a token which references the property named tokPropName
  104.     // of the object referenced by containerTok.  containerTok must not be
  105.     // a property token.
  106.  
  107. extern pascal void     InitPropertyMOSLTokenFromOtherProperty(MOSLToken *tok, const MOSLToken *propertyTok, DescType tokPropName);
  108.     // Initialises a token which references a property within the same object
  109.     // as an existing property token. propertyTok must be a property token.
  110.  
  111. extern pascal OSStatus MOSLTokenToDesc(const MOSLToken *tok, AEDesc *desc);
  112.     // Places a token in a descriptor.  The resulting descriptor type is always
  113.     // the same as tok->tokType.
  114.  
  115. extern pascal void     DescToMOSLToken(const AEDesc *tokDesc, MOSLToken *tok);
  116.     // Extracts a token from a descriptor containing a token.  tokDesc must
  117.     // contain a valid MOSLToken, typically placed there by MOSLTokenToDesc.
  118.     // Typically this routine is only called by code in "MoreOSL.c", which
  119.     // can consult the class table to ensure that the descriptor actually
  120.     // contains a token.
  121.     
  122. extern pascal OSStatus CompareMOSLTokens(DescType oper, const MOSLToken *tok1, const MOSLToken *tok2, Boolean *result);
  123.     // Compares two tokens using the given operator.  Currently only
  124.     // the kAEEquals operator is supported, and it assumes that the tokData
  125.     // field of the token is comparable.  You may need to modify this if
  126.     // you add extra fields to the token or you store weird native object
  127.     // pointers in the token or you want to support operators other than
  128.     // kAEEquals.
  129.